home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr11 / qwklay11.zip / QWK.TXT < prev   
Text File  |  1993-06-02  |  37KB  |  821 lines
  1.                          QWK Mail Packet File Layout
  2.                               by Patrick Y. Lee
  3.                        Version 1.0 - February 23, 1992
  4.  
  5. This document is Copyright 1992 by Patrick Y. Lee.
  6.  
  7. The QWK-format is Copyright 1987 by Sparkware.
  8.  
  9. All program names mentioned in this document are either Copyright or Trade-
  10. mark of respective owner(s).
  11.  
  12. The author provides this file as-is without warranty of any kind, either
  13. expressed or implied.  You are using the information in this file at your
  14. own discretion.  The author assumes no responsibilities for damages, either
  15. physically or financially, from the use of this information.
  16.  
  17. This document may be freely distributed by any means (electronically, pa-
  18. per, etc.), provided that it is distributed in its entirety.  Portions of
  19. this document may be reproduced without credit.
  20.  
  21.                               Table of Contents
  22.  
  23. 1.  Introduction
  24.     1.1.  Intent
  25.     1.2.  History
  26.     1.3.  Questions, corrections, etc.
  27. 2.  Conventions & overview
  28.     2.1.  The BBS ID
  29.     2.2.  Packet compression
  30.     2.3.  Packet transfer & protocols
  31.     2.4.  Limitations
  32. 3.  QWK files
  33.     3.1.  Naming convention
  34.     3.2.  Control file (CONTROL.DAT)
  35.     3.3.  Welcome file
  36.     3.4.  Goodbye file
  37.     3.5.  News file
  38.     3.6.  Qmail DeLuxe² menu file
  39.     3.7.  New uploads listing (NEWFILES.DAT)
  40.     3.8.  Bulletin file(s) (BLT-x.y)
  41.     3.9.  Message file (MESSAGES.DAT)
  42.     3.10.  Index files (*.NDX)
  43.         3.10.1.  Conference indices
  44.         3.10.2.  Personal index (PERSONAL.NDX)
  45.     3.11.  Pointer file
  46.     3.12.  SESSION.TXT
  47. 4.  REP files
  48.     4.1.  Naming convention
  49.     4.2.  Message file (BBSID.MSG)
  50.     4.3.  Door control messages
  51.     4.3.1.  DOOR.ID file
  52.     4.3.2.  Qmail
  53.     4.3.3.  MarkMail
  54.     4.3.4.  KMail
  55.     4.3.5.  RoseMail
  56.     4.3.6.  Complete Mail Door
  57.     4.4.  Turning off the echo flag
  58.     4.5.  Tag-lines
  59. 5.  Net mail
  60. A.  Credits & contributions
  61. B.  Sample Turbo Pascal and C code
  62. C.  Sample message
  63. D.  Sample index file
  64.  
  65.                         -=-=-=-=-=-=-<>-=-=-=-=-=-=-
  66.  
  67. To search for a specific section, look for "[x.x]" using your editor or
  68. viewer.  For example, to jump to the tag-lines portion of this file, search
  69. for "[4.5]" with your editor or text viewer.
  70.  
  71.                         -=-=-=-=-=-=-<>-=-=-=-=-=-=-
  72.  
  73. [1]  Introduction
  74.  
  75. [1.1]  Intent
  76.  
  77. This document is written to facilitate programmers who want to write
  78. QWK-format mail doors or readers.  It is intended to be a comprehen-
  79. sive reference covering all areas of QWK-format mail processing.  De-
  80. tailed break down of each file is included, as are implementation
  81. information.  In addition, door and reader specific information may be
  82. included, when such information are available to me.
  83.  
  84. [1.2]  History
  85.  
  86. The QWK-format was invented by Mark "Sparky" Herring in 1987.  It was
  87. based on Clark Development Corporation's PCBoard version 12.0 message
  88. base format.  Off-line mail reading has become popular only in recent
  89. years.  Prior to summer of 1990, there were only two QWK-format off-
  90. line mail reader programs.  They were Qmail DeLuxe by Mark Herring and
  91. EZ-Reader by Eric Cockrell.  Similarly for the doors, there were only
  92. two -- Qmail by Mark Herring and MarkMail by Mark Turner.  They were
  93. both for PCBoard systems.
  94.  
  95. A lot has changed in both off-line reader and mail door markets since
  96. summer 1990.  Now, there are more than a dozen off-line mail readers
  97. for the PC.  Readers for the Macintosh, Amiga, and Atari exist as
  98. well.  There are over a half dozen doors for PCBoard, and QWK-format
  99. doors exist for virtually all of the popular BBS softwares.  All of
  100. these happened in less than two years!  More readers and doors are in
  101. development as I write this, keep up the excellent work.  In addition
  102. to doors, some BBS softwares has QWK-format mail facility built in.
  103.  
  104. Off-line mail reading is an integral part of BBS calling.  Conference
  105. traffic and selection on all networks have grown dramatically in re-
  106. cent years that on-line reading is a thing of the past.  Off-line mail
  107. reading offers an alternative to reading mail on-line -- It offers
  108. speed that cannot be achieved with on-line mail reading.
  109.  
  110. The reason why QWK-format readers and doors seem to have gained popu-
  111. larity is probably dued to its openness.  The format is readily avail-
  112. able to any programmer who wishes to write a program that utilize it. 
  113. Proprietary is a thing of the past, it does not work!  Openness is
  114. here to stay and QWK-format is a part of it.
  115.  
  116. [1.3]  Questions, corrections, etc.
  117.  
  118. Most of the message networks today have a conference/echo devoted to
  119. discussion of off-line readers and mail doors.  The ones I know are on
  120. FidoNet, ILink, Intelec, and RIME.  If you have questions after read-
  121. ing anything in here, feel free to drop by any of the above confer-
  122. ence/echo and I am sure other QWK authors will try to help.
  123.  
  124. I can be reached in the Off-line conferences on RIME, ILink, and
  125. Intelec, as well as the Common conference on RIME.  Mail can be routed
  126. to node RUNNINGB.  I can be reached on the Internet at
  127. "p.lee@green.cooper.edu".  Any corrections, extensions, comments, and
  128. criticisms are welcomed.
  129.  
  130. [2]  Conventions & overview
  131.  
  132. All offsets referenced in this document will be relative to 1.  I am
  133. not a computer, I start counting at one, not zero!
  134.  
  135. Words which are enclosed in quotes should be entered as-is.  The quo-
  136. tations are not part of the string unless noted.
  137.  
  138. You may have noticed I use the phrase "mail program" or "mail facili-
  139. ty" instead of mail doors.  This is because some BBS softwares offer
  140. the option of creating QWK-format mail packets right from the BBS. 
  141. With those, there is no need for an external mail door.
  142.  
  143. [2.1]  The BBS ID
  144.  
  145. The BBS ID (denoted as BBSID) is a 1-8 characters word that identifies
  146. a particular BBS.  This identifier should be obtained from line 5 of
  147. the CONTROL.DAT file (see section 3.2.1).
  148.  
  149. [2.2]  Packet compression
  150.  
  151. Most mail packets are compressed when created by the mail door in
  152. order to save download time and disk space.  However, many off-line
  153. reader programs allow the user to unarchive a mail packet outside of
  154. the reader program, so the reader will not have to unarchive it.  Upon
  155. exit, the reader will not call the archiver to save it.  It is up to
  156. the user to archive the replies.  This is useful if the user has lim-
  157. ited memory and cannot shell out to DOS to run the unarchive program. 
  158. For readers based on non-PC equipment, the user may be using less
  159. common compression program that does not have command line equivalent.
  160.  
  161. [2.3]  Packet transfer & protocols
  162.  
  163. There is no set rule on what transfer protocol should be used.  Howev-
  164. er, it would be nice for the mail program on the BBS to provide the
  165. Sysop with options as to what to offer.  This should be a configura-
  166. tion option for the user.
  167.  
  168. [2.4]  Specifications & limitations
  169.  
  170. There aren't many known limits in the QWK specification.  However,
  171. various networks seem to impose artificial limits.  On many of the PC-
  172. based networks, 99-lines appears to be the upper limit for some
  173. softwares.  However, most of the readers can handle more than that. 
  174. Reader authors reading this may want to offer the option to split
  175. replies into n lines each (the actual length should be user definable
  176. so when the network software permits, the user can increase this num-
  177. ber).
  178.  
  179. [3]  QWK files
  180.  
  181. [3.1]  Naming convention
  182.  
  183. Generally, the name of the mail packet is BBSID.QWK.  However, this
  184. does not have to be the case.  When the user downloads more than one
  185. mail packet at one time, either the mail program or the transfer pro-
  186. tocol program will rename the second and subsequent mail packets to
  187. other names.  They will either change the file extension or add a
  188. number to the end of the filename.  In either case, you should not
  189. rely on the name of the QWK file as the BBSID.  The BBSID, as men-
  190. tioned before, should be obtained from line 5 of the CONTROL.DAT file. 
  191. In addition, mail packets do not have to end with QWK extension ei-
  192. ther.  The user may choose to name them with other file extensions.
  193.  
  194. [3.2]  Control file (CONTROL.DAT)
  195.  
  196. The CONTROL.DAT file is a simple ASCII file.  Each line is terminated
  197. with a carriage return and line feed combination.  All lines should
  198. start on the first column.
  199.  
  200. Line #
  201.  1   My BBS                   BBS name
  202.  2   New York, NY             BBS city and state
  203.  3   212-555-1212             BBS phone number
  204.  4   John Doe, Sysop          BBS Sysop name
  205.  5   20052,MYBBS              Mail door registration #, BBSID
  206.  6   01-01-1991,23:59:59      Mail packet creation time
  207.  7   JANE DOE                 User name (upper case)
  208.  8                            Name of menu for Qmail, blank if none
  209.  9   0                        ? Seem to be always zero
  210. 10   0                        ? Seem to be always zero
  211. 11   121                      Total number of conference minus 1
  212. 12   0                        1st conf. number
  213. 13   Main Board               1st conf. name (13 characters or less)
  214. 14   1                        2nd conf. number
  215. 15   General                  2nd conf. name
  216. ..   3                        etc. onward until it hits max. conf.
  217. ..   123                      Last conf. number
  218. ..   Amiga_I                  Last conf. name
  219. ..   HELLO                    Welcome screen file
  220. ..   NEWS                     BBS news file
  221. ..   SCRIPT0                  Log off screen
  222.  
  223. Some mail doors, such as MarkMail, will send additional information
  224. about the user from here on.
  225.  
  226. 0                             ?
  227. 25                            Screen length on the BBS
  228. JANE DOE                      User name in uppercase
  229. Jane                          User first name in mixed case
  230. NEW YORK, NY                  User city information
  231. 718 555-1212                  User data phone number
  232. 718 555-1212                  User home phone number
  233. 108                           Security level
  234. 00-00-00                      Expiration date
  235. 01-01-91                      Last log on date
  236. 23:59                         Last log on time
  237. 999                           Log on count
  238. 0                             Current conference number on the BBS
  239. 0                             Total KB downloaded
  240. 999                           Download count
  241. 0                             Total KB uploaded
  242. 999                           Upload count
  243. 999                           Minutes per day
  244. 999                           Minutes remaining today
  245. 999                           Minutes used this call
  246. 32767                         Max. download KB per day
  247. 32767                         Remaining KB today
  248. 0                             KB downloaded today
  249. 23:59                         Current time on BBS
  250. 01-01-91                      Current date on BBS
  251. My BBS                        BBS network tag-line
  252. 0                             ?
  253.  
  254. Some mail doors will offer the option of sending an abbreviated con-
  255. ference list.  That means the list will contain only conferences the
  256. user has selected.  This is done because some mail readers cannot
  257. handle more than n conferences at this time.  Users using those read-
  258. ers will need this option if the BBS they call have too many confer-
  259. ences.
  260.  
  261. [3.3]  Welcome file
  262.  
  263. This file usually contains the log on screen from the BBS.  The exact
  264. filename is specified in the CONTROL.DAT file, after the conference
  265. list.  This file may be in any format the Sysop chooses it be -- usu-
  266. ally either in plain ASCII or with ANSI screen control code.  Some
  267. Sysops (notably PCBoard Sysops) may use BBS-specific color change code
  268. in this file as well.  Current mail programs seem to handle the trans-
  269. lations between BBS-specific code to ANSI based screen control codes.
  270.  
  271. Even if the CONTROL.DAT file contains the filename of this file, it
  272. may not actually exist in the mail packet.  Sometimes, users will
  273. manually delete this file before entering the mail reader.  Some off-
  274. line readers offer the option to not display this welcome screen; some
  275. will display this file regardless.  Some doors, similarly, will offer
  276. option to the user to not send this file.
  277.  
  278. [3.4]  Goodbye file
  279.  
  280. Similar to the welcome file above, the filename to the goodbye file is
  281. in the CONTROL.DAT file.  This is the file the BBS displays when the
  282. user logs off the board.  It is optional, as always, to send this file
  283. or to display it.
  284.  
  285. [3.5]  News file
  286.  
  287. Many mail doors offer the option to send the news file from the BBS. 
  288. Most will only send this when it has been updated.  Like the welcome
  289. and goodbye files, the filename to the news file is found in the CON-
  290. TROL.DAT file.  It can be in any format the Sysop chooses, but usually
  291. in either ASCII or ANSI.  Like the welcome screen, current mail facil-
  292. ities seem to handle translation between BBS-specific control codes to
  293. ANSI screen control codes.
  294.  
  295. [3.6]  Qmail DeLuxe² menu file
  296.  
  297. This file is of use only for Qmail DeLuxe² mail reader by Sparkware. 
  298. The filename is found on line 8 of the CONTROL.DAT file.
  299.  
  300. [3.7]  New uploads listing (NEWFILES.DAT)
  301.  
  302. Most mail programs on the BBS will offer the option to scan new files
  303. uploaded to the BBS.  The result is found in a file named
  304. NEWFILES.DAT.  The mail program, if implementing this, should update
  305. the last file scan field in the user's profile, if there is such a
  306. field, as well as other information required by the BBS.  The mail
  307. program should, of course, scan new files only in those areas the user
  308. is allowed access.
  309.  
  310. [3.8]  Bulletin files (BLT-x.y)
  311.  
  312. Most mail programs will also offer the option to include updated bul-
  313. letin files found on the BBS in the mail packet.  The bulletins are
  314. named BLT-x.y, where x is the conference/echo the bulletin came from,
  315. and y the bulletin's actual number.  The mail program will have to
  316. take care of updating the last read date on the bulletins in the user
  317. record.
  318.  
  319. [3.9]  Message file (MESSAGES.DAT)
  320.  
  321. The MESSAGES.DAT file is the most important.  This is where all of the
  322. messages are contained in.  The QWK file format is based on PCBoard
  323. 12.0 message base format from Clark Development Corporation (maker of
  324. PCBoard BBS software).
  325.  
  326. The file has a logical record length of 128-bytes.  The first record
  327. of MESSAGES.DAT always contain a copyright notice saying "Produced by
  328. Qmail...Copyright (c) 1987 by Sparkware.  All Rights Reserved".  The
  329. rest of the record is space filled.  Actual messages consist of a 128-
  330. bytes header, plus one or more 128-bytes block with the message text. 
  331. Actual messages start in record 2.  The header block is layed out as
  332. follows:
  333.  
  334. Offset  Length  Description
  335. ------  ------  ----------------------------------------------------   
  336.     1       1   Message status flag (unsigned character)
  337.                 ' ' = public, unread
  338.                 '-' = public, read
  339.                 '+' = private, unread
  340.                 '*' = private, read
  341.                 '~' = comment to Sysop, unread
  342.                 '`' = comment to Sysop, read
  343.                 '%' = password protected, unread
  344.                 '^' = password protected, read
  345.                 '!' = group password, unread
  346.                 '#' = group password, read
  347.                 '$' = group password to all
  348.     2       7   Message number (in ASCII)
  349.     9       8   Date (mm-dd-yy, in ASCII)
  350.    17       5   Time (24 hour hh:mm, in ASCII)
  351.    22      25   To (uppercase, left justified)
  352.    47      25   From (uppercase, left justified)
  353.    72      25   Subject of message (mixed case)
  354.    97      12   Password (space filled)
  355.   109       8   Reference message number (in ASCII)
  356.   117       6   Number of 128-bytes blocks in message (including the
  357.                 header, in ASCII; the lowest value should be 2, header
  358.                 plus one block message; this number may not be left
  359.                 flushed within the field)
  360.   123       1   Flag (ASCII 225 means message is active; ASCII 226
  361.                 means this message is to be killed)
  362.   124       2   Conference number (unsigned word)
  363.   126       2   Not used (usually filled with spaces or nulls)
  364.   128       1   Indicates whether the message has a network tag-line
  365.                 or not.  A value of '*' indicates that a network tag-
  366.                 line is present; a value of ' ' (space) indicates
  367.                 there isn't one.  Messages sent to readers (non-net-
  368.                 status) generally leave this as a space.  Only network
  369.                 softwares need this information.
  370.  
  371. Fields such as To, From, Subject, Message #, Reference #, and the like
  372. are space padded if they are shorter than the field's length.
  373.  
  374. The message text starts in the next record.  You can find out how many
  375. blocks make up one message by looking at the value of "Number of 128
  376. byte blocks".  Instead of carriage return and line feed combination,
  377. each line in the message end with an ASCII 227 (pi character) symbol. 
  378. There are reports that some (buggy) readers have problems with mes-
  379. sages which do not end the last line in the message with an ASCII 227. 
  380. If a message does not completely occupy the 128-bytes block, the re-
  381. mainder of the block is padded with space or null.
  382.  
  383. Note that there seems to exist old doors which will use one byte to
  384. represent the conference number and pad the other one with an ASCII 32
  385. character.  The program reading this information will have to deter-
  386. mine whether the ASCII 32 in byte 125 of the header is a filler or
  387. part of the unsigned word.  One method is to look in the CONTROL.DAT
  388. file to determine the highest conference number.
  389.  
  390. Even though most mail programs will generate MESSAGES.DAT files that
  391. appear in conference order, this is not always the case.  Tomcat!
  392. (mail door for Wildcat! BBS) generates MESSAGES.DAT that is not in
  393. conference order.  This is due to how Wildcat! itself stores mail on
  394. the BBS.
  395.  
  396. Note that some mail doors offer the option of sending a mail packet
  397. even though there may be no messages to send -- thus an empty MESSAG-
  398. ES.DAT file.  This was tested with Qmail 4.0 door and it sent a MES-
  399. SAGES.DAT file that contains a few empty 128-bytes blocks.
  400.  
  401. [3.10]  Index files (*.NDX)
  402.  
  403. [3.10.1]  Conference indices
  404.  
  405. The index files contain a list of pointers pointing to the beginning
  406. of messages in the MESSAGES.DAT file.  The pointer is in terms of the
  407. 128-bytes block logical record that the MESSAGES.DAT file is in.  Each
  408. conference has its own xxx.NDX file, where xxx is the conference num-
  409. ber left padded with zeroes.  Some mail programs offer the user the
  410. option to not generate index files.  So the mail readers need to cre-
  411. ate the index files if they are missing.
  412.  
  413. EZ-Reader 1.xx versions will convert the NDX files from Microsoft MKS
  414. format into IEEE long integer format.  The bad part about this is that
  415. the user may store those index files back into the QWK file.  When
  416. another reader reads the index files, it will be very confused!
  417.  
  418. Special note for BBSes with more than 999 conferences: Index files for
  419. conferences with four digit conference numbers is named xxxx.NDX,
  420. where xxxx is the conference number (left padded with zeroes).  The
  421. filenames for three digit conferences are still named xxx.NDX on these
  422. boards.  I would assume filenames for conferences in the five digit
  423. range is xxxxx.NDX, but I have not seen a BBS with 10,000 or more
  424. conferences yet!
  425.  
  426. Each NDX file uses a five bytes logical record length and is formatted
  427. to:
  428.  
  429. Offset  Length  Description
  430. ------  ------  ------------------------------------------------------
  431.     1       4   Record number pointing to corresponding message in
  432.                 MESSAGES.DAT.  This number is in the Microsoft MKS$
  433.                 BASIC format.
  434.     5       1   Conference number of the message.  This byte should
  435.                 not be used because it duplicates both the filename of
  436.                 the index file and the conference # in the header.  It
  437.                 is also one byte long, which is insufficient to handle
  438.                 conferences over 255.
  439.  
  440. Please refer to appendix B for routines to deal with MKS numbers.
  441.  
  442. [3.10.2]  Personal index (PERSONAL.NDX)
  443.  
  444. There is a special index file named PERSONAL.NDX.  This file contains
  445. pointers to messages which are addressed to the user, i.e. personal
  446. messages.  Some mail door and utility programs also allow the selec-
  447. tion of other messages to be flagged as personal messages.
  448.  
  449. [3.11]  Pointer file
  450.  
  451. Pointer file is generally included so that the user can reset the last
  452. read pointers on the mail program, in case there is a crash on the BBS
  453. or some other mishaps.  There should be little reason for the reader
  454. program to access the pointer file.
  455.  
  456. The pointer files I have seen are:
  457.  
  458. Qmail          BBSID.PTR
  459. MarkMail       BBSID.PNT
  460. KMail          BBSID.PNT
  461. SFMailQwk      BBSID.SFP
  462.  
  463. Additions to this list are welcomed.
  464.  
  465. [3.12]  SESSION.TXT
  466.  
  467. This file, if included, will contain the message scanning screen the
  468. user sees from the door.
  469.  
  470. [4]  REP files
  471.  
  472. [4.1]  Naming convention
  473.  
  474. The reply file is named BBSID.MSG, where BBSID is the ID code for the
  475. BBS found on line 5 of the CONTROL.DAT file.  Once this file has been
  476. created, the mail reader can archive it up into a file with REP exten-
  477. sion.
  478.  
  479. [4.2]  Message file (BBSID.MSG)
  480.  
  481. Replies use the same format as the MESSAGES.DAT file, except that mes-
  482. sage number field will contain the conference number instead.  In
  483. other words, the conference number will be placed in the two bytes
  484. (binary) starting at offset 124, as well as the message number field
  485. (ASCII) at offset 2.
  486.  
  487. The first 128-bytes record of the file is the header.  Instead of the
  488. copyright notice, it contains the BBSID of the BBS.  This 1-8 charac-
  489. ter BBSID must start at the very first byte and must match what the
  490. BBS has.  The rest of the record is space padded.  The replies start
  491. at record 2.  Each reply message will have a 128-bytes header, plus
  492. one or more for the message text; followed by another header, and so
  493. on.
  494.  
  495. The mail program must check to make sure the BBSID in the first block
  496. of the BBSID.MSG file matches what the BBS has!
  497.  
  498. [4.3]  Door control messages
  499.  
  500. These messages allow the user to change their setup on the BBS by
  501. simply entering a message.  The goal is to allow the user to be able
  502. to control most areas of the BBS via the mail door.  Different mail
  503. doors have different capabilities.  Most all of them offer the ability
  504. to add and drop a conference, as well as reset the last read pointers
  505. in a conference.
  506.  
  507. [4.3.1]  DOOR.ID file
  508.  
  509. The DOOR.ID file was first introduced by Greg Hewgill with Tomcat!
  510. mail door and SLMR mail reader.  Since then, many other authors have
  511. picked up this idea and use the format.  This file provides the neces-
  512. sary identifiers a reader needs to send add, drop, etc. messages to
  513. the mail door.  It tells the reader who to address the message to and
  514. what can be put in the subject line.
  515.  
  516. DOOR = <doorname>             This is the name of the door that creat-
  517.                               ed the QWK packet, i.e. <doorname> =
  518.                               Tomcat.
  519. VERSION = <doorversion>       This is the version number of the door
  520.                               that created the packet, i.e.
  521.                               <doorversion> = 2.9.
  522. SYSTEM = <systemtype>         This is the underlying BBS system type
  523.                               and version, i.e. <systemtype> = Wildcat
  524.                               2.55.
  525. CONTROLNAME = <controlname>   This is the name to which the reader
  526.                               should send control messages, eg.
  527.                               <controlname> = TOMCAT.
  528. CONTROLTYPE = <controltype>   This can be one of ADD, DROP, REQUEST,
  529.                               or others.  ADD and DROP are pretty
  530.                               obvious (they work as in MarkMail), and
  531.                               REQUEST is for use with BBS systems that
  532.                               support file attachments.  Try out SLMR
  533.                               with CONTROLTYPE = REQUEST and use the Q
  534.                               function.  (This seems to be a Wildcat!
  535.                               BBS feature.)
  536. RECEIPT                       This flag indicates that the door/BBS is
  537.                               capable of return receipts when a mes-
  538.                               sage is received.  If the first three
  539.                               letters of the subject are RRR, then the
  540.                               door should strip the RRR and set the
  541.                               'return-receipt-requested' flag on the
  542.                               corresponding message.
  543.  
  544. None of the lines are actually required and they may appear in any
  545. order.  Of course, you would need a CONTROLNAME if you have any
  546. CONTROLTYPE lines.
  547.  
  548. [4.3.2]  Qmail
  549.  
  550. Send a message addressed to "QMAIL" with a subject of "CONFIG".  Then,
  551. enter any of the commands listed below inside the text of your mes-
  552. sage.  Remember to use one command per line.
  553.  
  554. ADD <confnum>            Add a conference into the Qmail Door scanning
  555.                          list.  "YOURS" can also be added to the com-
  556.                          mand if the user wishes to receive messages
  557.                          only addressed them.  i.e. "ADD 1 YOURS"
  558. DROP <confnum>           Drop a conference from the Qmail Door scan-
  559.                          ning list.
  560. RESET <confnum> <value>  Resets a conference to a particular value.
  561.                          The user can use "HIGH-xxx" to set the con-
  562.                          ference to the highest message in the base.
  563. CITY <value>             Changes the "city" field in the user's
  564.                          PCBoard entry.
  565. PASSWORD <value>         Changes the user's login password.
  566. BPHONE <value>           Business/data phone number
  567. HPHONE <value>           Home/voice phone number
  568. PCBEXPERT <on|off>       Turns the PCBoard expert mode ON or OFF.
  569. PCBPROT <value>          PCBoard file transfer protocol (A-Z).
  570. PAGELEN <value>          Set page length inside PCBoard.
  571. PCBCOMMENT <value>       Set user maintained comment.
  572. AUTOSTART <value>        Qmail Door autostart command.
  573. PROTOCOL <value>         Qmail Door file transfer protocol (A-Z).
  574. EXPERT <ON or OFF>       Turns the Qmail Door expert mode ON or OFF.
  575. MAXSIZE <value>          Maximum size of the user's .QWK packet (in
  576.                          bytes)
  577. MAXNUMBER <value>        Maximum number of messages per conference.
  578.  
  579. [4.3.3]  MarkMail
  580.  
  581. Send a message addressed to "MARKMAIL" with the subject line saying:
  582.  
  583. ADD [value]         in the conference you want to add
  584. DROP                in the conference you want to drop
  585. YOUR [value]        in the conference you want only your mail sent
  586. YA [value]          in the conference you want only your mail + mail
  587.                     addressed to "ALL"
  588. FILES ON or OFF     in any conference to tell MarkMail whether to scan
  589.                     for new files or not.
  590. BLTS ON or OFF      to turn on and off, respectively, of receiving
  591.                     bulletins.
  592. OWN ON or OFF       to turn on and off, respectively, of receiving
  593.                     messages you sent
  594. DELUXE ON or OFF    to turn on and off, respectively, of receiving
  595.                     DeLuxe menu
  596. LIMIT <size>        to set the maximum size of MESSAGES.DAT file can
  597.                     be, it cannot exceed what the Sysop has set up
  598.  
  599. An optional number can be added onto the commands "ADD", "YOUR", and
  600. "YA".  If this number is positive, then it will be treated as an abso-
  601. lute message number.  MarkMail will set your last read pointer to that
  602. number.  If it is negative, MarkMail will set your last read pointer
  603. to the highest minus that number.  For example: "ADD -50" will add the
  604. conference and set the last read pointer to the highest in the confer-
  605. ence minus 50.
  606.  
  607. [4.3.4]  KMail
  608.  
  609. Send a private message addressed to "KMAIL" in the conference that you
  610. want to add, drop, or reset.  The commands are "ADD", "DROP", and
  611. "RESET #", respectively.  The "#" is the message number you want your
  612. last read pointer in the conference be set to.
  613.  
  614. [4.3.5]  RoseMail
  615.  
  616. The RoseMail door allows configuration information be placed in either
  617. the subject line or message text.  The message must be addressed to
  618. "ROSEMAIL".  For only one command, it can be placed in the subject
  619. line.  For more than one changes, the subject line must say "CONFIG"
  620. and each change be placed in the message text.  Every line should be
  621. left justified.  Valid commands are:
  622.  
  623. Command                                           Example
  624. ───────────────────────────────────────────────── ──────────────────
  625. ADD <Conference> [<Message #>] [<Yours>]          ADD 2 -3 Y
  626. DROP <Conference>                                 DROP 2
  627. RESET <Conference> <Message #>                    RESET 12 5000
  628. PCBEXPERT <ON | OFF> - PCBoard expert mode        PCBEXPERT ON
  629. EXPERT <ON | OFF>    - RoseMail expert mode       EXPERT OFF
  630. PCBPROT <A - Z>      - PCBoard protocol           PCBPROT Z
  631. PROT <A - Z>         - RoseMail protocol          PROT G
  632. PAGELEN <Number>     - Page length                PAGELEN 20
  633. MAXSIZE <Kbytes>     - Max packet size in Kb      MAXSIZE 100
  634. MAXNUMBER <max msgs/conference>                   MAXNUMBER 100
  635. JUMPSTART <Sequence or OFF>                       JUMPSTART D;Y;Q
  636. MAXPACKET <max msgs/packet>                       MAXPACKET 500
  637. AUTOSTART <Sequence or OFF> - same as jumpstart   AUTOSTART OFF
  638. OPT <##> <ON | OFF>  - set door option            OPT 2 OFF
  639.  
  640. [4.3.6]  Complete Mail Door
  641.  
  642. Send message to "CMPMAIL", the commands are "ADD" and "DROP".  This
  643. message must be sent in the conference that you want to add or drop.
  644.  
  645. [4.4]  Turning off the echo flag
  646.  
  647. In order to send a non-echoed message (not send out to other BBSes), a
  648. user can enter "NE:" in front of the subject line.  The mail program
  649. will strip this "NE:" and turn off the echo flag.  This feature may
  650. not be offered in all mail doors.
  651.  
  652. [4.5]  Tag-lines
  653.  
  654. The most common format for a reader tag-line is:
  655.  
  656. ---
  657.  ■ My reader v1.00 ■ The rest of the tag-line.
  658.  
  659. The three dashes is called a tear-line.  The tag-line is appended to
  660. the end of the message and is usually one line only.  It is preferred
  661. that tag-lines conform to this format so that networking softwares
  662. such as QNet and RNet will not add another tearline to the message
  663. when they process it.
  664.  
  665. Softwares on FidoNet does not like mail readers adding a tear-line of
  666. their own, so if your mail reader offers a FidoNet mode, you will need
  667. to get rid of the tear-line.  Another item which differs between the
  668. FidoNet and PC-based networks is that FidoNet does not like extended
  669. ASCII characters.  So your reader may want to strip high ASCII if the
  670. user has FidoNet mode on.  Acceptable tag-line style, I believe, is
  671. just this:
  672.  
  673.  * My Reader v1.00 * The rest of the tag-line.
  674.  
  675. [5]  Net mail
  676.  
  677. I do not have complete information of net-mail implementation using
  678. QWK-format.  Someone please fill me in the details.
  679.  
  680.                      -=-=-=-=-=-=-<>-=-=-=-=-=-=-
  681.  
  682. [A]  Credits and Contributions
  683.  
  684. Mark "Sparky" Herring, who originated the QWK-format.
  685.  
  686. Tim Farley, who started this documentation back in the summer of 1990. 
  687. The general outline here is the work of Tim.  I filled in the blanks.
  688.  
  689. Jeffery Foy, who gave us the format for Microsoft single binary versus
  690. IEEE format.
  691.  
  692. Greg Hewgill, who (if I remember correctly) wrote the Turbo Pascal
  693. routines (included in here) to convert between MKS and TP LongInt.
  694.  
  695. Dennis McCunney, who is the host of the Off-line conference on RIME,
  696. is very knowledgeable in off-line reading concept and programs.  His
  697. goal is to have one reader that can read mail packet from any source.
  698.  
  699. All those who have been around the Off-line conferences on ILink (the
  700. oldest of the three I participate), RIME, and Intelec, who have pro-
  701. vided great help over the past two years.  The bulk of the information
  702. presented here are from messages in those conferences.  These people
  703. include, but are no limited to, the followings: Dane Beko, Joseph
  704. Carnage, Marcos Della, Joey Lizzi, Mark May, and Jim Smith.
  705.  
  706. [B]  Sample Turbo Pascal and C code
  707.  
  708. Here are a few routines in Turbo Pascal and C to convert Microsoft
  709. BASIC MKS format to usable IEEE long integer.  These are collected
  710. over the networks and there is no guarantee that they will work for
  711. you!
  712.  
  713. Turbo Pascal (Greg Hewgill ?):
  714.  
  715. type
  716.      bsingle = array [0..3] of byte;
  717.  
  718. { converts TP real to Microsoft 4 bytes single }
  719.  
  720. procedure real_to_msb (preal : real; var b : bsingle);
  721. var
  722.      r : array [0 .. 5] of byte absolute preal;
  723. begin
  724.      b [3] := r [0];
  725.      move (r [3], b [0], 3);
  726. end; { procedure real_to_msb }
  727.  
  728. { converts Microsoft 4 bytes single to TP real }
  729.  
  730. function msb_to_real(b : bsingle) : real;
  731. var
  732.      preal : real;
  733.      r : array [0..5] of byte absolute preal;
  734. begin
  735.      r [0] := b [3];
  736.      r [1] := 0;
  737.      r [2] := 0;
  738.      move (b [0], r [3], 3);
  739.      msb_to_real := preal;
  740. end; { procedure msb_to_real }
  741.  
  742. C (identify yourself if you originated this routine):
  743.  
  744. /* converts 4 bytes Microsoft MKS format to long integer */
  745.  
  746. unsigned long mbf_to_int (m1, m2, m3, exp)
  747. unsigned int m1, m2, m3, exp;
  748. {
  749.      return (((m1 + ((unsigned long) m2 << 8) + ((unsigned long) m3 <<
  750.      16)) | 0x800000L) >> (24 - (exp - 0x80)));
  751. }
  752.  
  753. Microsoft binary (by Jeffery Foy):
  754.  
  755.    31 - 24    23     22 - 0        <-- bit position
  756. +-----------------+----------+
  757. | exponent | sign | mantissa |
  758. +----------+------+----------+
  759.  
  760. IEEE (C/Pascal/etc.):
  761.  
  762.    31     30 - 23    22 - 0        <-- bit position
  763. +----------------------------+
  764. | sign | exponent | mantissa |
  765. +------+----------+----------+
  766.  
  767. In both cases, the sign is one bit, the exponent is 8 bits, and the
  768. mantissa is 23 bits.  You can write your own, optimized, routine to
  769. convert between the two formats using the above bit layout.
  770.  
  771. [C]  Sample message
  772.  
  773. Here is a sample message in hex and ASCII format:
  774.  
  775. 019780  20 34 32 33 32 20 20 20 30 32 2D 31 35 2D 39 32   4232   02-15-92
  776. 019790  31 33 3A 34 35 52 49 43 48 41 52 44 20 42 4C 41  13:45RICHARD BLA
  777. 0197A0  43 4B 42 55 52 4E 20 20 20 20 20 20 20 20 53 54  CKBURN        ST
  778. 0197B0  45 56 45 20 43 4F 4C 45 54 54 49 20 20 20 20 20  EVE COLETTI     
  779. 0197C0  20 20 20 20 20 20 20 51 45 44 49 54 20 48 41 43         QEDIT HAC
  780. 0197D0  4B 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
  781. 0197E0  20 20 20 20 20 20 20 20 20 20 20 20 34 30 33 36              4036
  782. 0197F0  20 20 20 20 37 20 20 20 20 20 E1 0A 01 00 00 20      7     ß
  783. 019800  2A 20 49 6E 20 61 20 6D 65 73 73 61 67 65 20 64  * In a message d
  784. 019810  61 74 65 64 20 30 32 2D 30 39 2D 39 32 20 74 6F  ated 02-09-92 to
  785. 019820  20 53 74 65 76 65 20 43 6F 6C 65 74 74 69 2C 20   Steve Coletti, 
  786. 019830  52 69 63 68 61 72 64 20 42 6C 61 63 6B 62 75 72  Richard Blackbur
  787. 019840  6E 20 73 61 69 64 3A E3 E3 52 42 3E 53 43 20 AF  n said:ππRB>SC »
  788. 019850  20 65 64 69 74 6F 72 20 69 6E 20 74 68 65 20 28   editor in the (
  789. 019860  6D 61 69 6E 66 72 61 6D 65 29 20 56 4D 2F 43 4D  mainframe) VM/CM
  790. 019870  53 20 70 72 6F 64 75 63 74 20 6C 69 6E 65 20 69  S product line i
  791. [ etc. ]
  792. 019A00  6E 6F 74 20 61 20 44 6F 63 74 6F 72 2C 20 62 75  not a Doctor, bu
  793. 019A10  74 20 49 20 70 6C 61 79 20 6F 6E 65 20 61 74 20  t I play one at 
  794. 019A20  74 68 65 20 48 6F 73 70 69 74 61 6C 2E E3 20 20  the Hospital.π  
  795. 019A30  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
  796. 019A40  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
  797. 019A50  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
  798. 019A60  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
  799. 019A70  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
  800. 019A80  E3 50 43 52 65 6C 61 79 3A 4D 4F 4F 4E 44 4F 47  πPCRelay:MOONDOG
  801. 019A90  20 2D 3E 20 23 33 35 20 52 65 6C 61 79 4E 65 74   -> #35 RelayNet
  802. 019AA0  20 28 74 6D 29 E3 34 2E 31 30 20 20 20 20 20 20   (tm)π4.10      
  803. 019AB0  20 20 20 20 20 20 20 20 20 48 55 42 4D 4F 4F 4E           HUBMOON
  804. 019AC0  2D 4D 6F 6F 6E 44 6F 67 20 42 42 53 2C 20 42 72  -MoonDog BBS, Br
  805. 019AD0  6F 6F 6B 6C 79 6E 2C 4E 59 20 37 31 38 20 36 39  ooklyn,NY 718 69
  806. 019AE0  32 2D 32 34 39 38 E3 20 20 20 20 20 20 20 20 20  2-2498π         
  807. 019AF0  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
  808.  
  809. [D]  Sample index file
  810.  
  811. Here is a sample index file in hex format:
  812.  
  813. 000000  00 00 28 87 19 00 00 30 87 19 00 00 38 87 19 00
  814. 000010  00 7E 87 19 00 00 07 88 19 00 00 0B 88 19 00 00
  815. 000020  0F 88 19 00 00 14 88 19 00 00 19 88 19 00 00 1E
  816. 000030  88 19 00 00 22 88 19 00 00 27 88 19 00 00 2C 88
  817. 000040  19 00 00 31 88 19 00 00 3B 88 19 00 00 40 88 19
  818. 000050  00 00 46 88 19 00 00 49 88 19 00 00 4D 88 19 00
  819. 000060  00 52 88 19 00 00 55 88 19 00 00 59 88 19 00 00
  820. 000070  60 88 19 00 00 66 88 19 00 00 70 88 19
  821.